---
title: 頁面
description: Astro 頁面簡介
i18nReady: true
---

import ReadMore from '~/components/ReadMore.astro';
import Since from '~/components/Since.astro'

**頁面** 是 Astro 專案 `src/pages/` 子目錄下的檔案，用來處理路由、資料載入以及網站內所有頁面的版面。

## 支援的頁面檔案類型

Astro 支援下列在 `src/pages/` 目錄裡的檔案類型：
- [`.astro`](#astro-頁面)
- [`.md`](#markdownmdx-頁面)
- `.mdx`（在安裝 [MDX 整合](/zh-tw/guides/integrations-guide/mdx/#installation)的情況下）
- [`.html`](#html-頁面)
- `.js`/`.ts`（作為[端點](/zh-tw/guides/endpoints/)）

## 基於檔案的路由

Astro 使用**基於檔案的路由**策略（file-based routing）。每個 `src/pages/` 目錄下的檔案，都會根據檔案的路徑，變成網站的端點。

如果你的內容位於[內容合集](/zh-tw/guides/content-collections/)或 [CMS](/zh-tw/guides/cms/)，也能透過[動態路由](/zh-tw/guides/routing/#dynamic-routes)功能，讓單一路由檔案產生多個頁面。

<ReadMore>進一步了解 [Astro 的路由](/zh-tw/guides/routing/)。</ReadMore>

### 連結至頁面

你可以用一般的 HTML [`<a>` 元素](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)連結到你網站的其他頁面。記得使用**相對於根網域的網址**，而非檔案相對路徑。

舉例來說，如果要從 `example.com` 的其他頁面連到 `https://example.com/authors/sonali/`：

```astro title="src/pages/index.astro"
Read more <a href="/authors/sonali/">about Sonali</a>.
```

## Astro 頁面

Astro 頁面使用 `.astro` 副檔名，支援的功能同 [Astro 元件](/zh-tw/basics/astro-components/)。

```astro title="src/pages/index.astro"
---
---
<html lang="en">
  <head>
    <title>我的首頁</title>
  </head>
  <body>
    <h1>歡迎來到我的網站！</h1>
  </body>
</html>
```

Astro 頁面必須產生完整的 HTML 文件，因此 Astro 預設會替 `src/pages/` 的 Astro 元件加上必要的 `<!DOCTYPE html>` 和 `<head>` 標籤（除非檔案已包含這些標籤）。如果不想要這個行為，可以將 Astro 元件標記為[局部](#局部頁面)頁面。

為了避免在每個頁面避免寫相同的 HTML 元素，你可以將常用到的 `<head>` 和 `<body>` 移到你自己的[版面元件](/zh-tw/basics/layouts/)，數量不限。

```astro {3} /</?MySiteLayout>/
---
// src/pages/index.astro
import MySiteLayout from '../layouts/MySiteLayout.astro';
---
<MySiteLayout>
  <p>我的頁面內容包在一層版面裡！</p>
</MySiteLayout>
```

<ReadMore>進一步了解[版面元件](/zh-tw/basics/layouts/)。</ReadMore>

## Markdown/MDX 頁面

Astro 也會將任何 `src/pages/` 內的 Markdown（`.md`）檔作為你最後網站的頁面。如果你有[安裝 MDX 整合](/zh-tw/guides/integrations-guide/mdx/#installation)的話，它也會對 MDX（`.mdx`）檔做同樣的事。這普遍用於以文字為主的頁面，像是部落格文章和文件。

此外，`src/content/` 的 [Markdown 或 MDX 頁面內容合集](/zh-tw/guides/content-collections/)可以[動態產生頁面](/zh-tw/guides/routing/#dynamic-routes)。

頁面版面在 [Markdown 檔](#markdownmdx-頁面)特別地有用。Markdown 檔可以使用特殊的 `layout` frontmatter 屬性指定 [版面元件](/zh-tw/basics/layouts/)，進而將 Markdown 內容包進完整的 `<html>...</html>` 頁面檔案裡。

```md {3}
---
# Example: src/pages/page.md
layout: '../layouts/MySiteLayout.astro'
title: '我的 Markdown 頁面'
---
# Title

這是我的網頁，用 **Markdown** 寫的喔！
```

<ReadMore>進一步了解如何在 Astro 使用 [Markdown](/zh-tw/guides/markdown-content/)。</ReadMore>

## HTML 頁面

擁有 `.html` 副檔名的檔案可以放置在 `src/pages/` 內，直接作為網站的頁面，但要注意 [HTML 元件](/zh-tw/basics/astro-components/#html-元件)不支援部分 Astro 功能。

## 自訂 404 錯誤頁面

如要自訂 404 錯誤頁面，可以在 `/src/pages` 新增 `404.astro` 或 `404.md`。

構建時會產生 `404.html` 頁面，大多數的[部署服務](/zh-tw/guides/deploy/)會找到並使用該檔案。

## 局部頁面

<p><Since v="3.4.0" /></p>

:::caution
局部頁面應該搭配 [htmx](https://htmx.org/) 或 [Unpoly](https://unpoly.com/) 這種前端套件一起使用。如果不介意寫低階前端 JavaScript 的話，你也可以使用它。考量到這點，它算是進階功能。

除此之外，如果元件包含 scoped styles 或 scripts，則不應使用局部頁面，因為那些元素不會包含在最終輸出的 HTML。如果需要 scoped styles，最好使用一般非局部的頁面，再搭配知道如何把內容合併到 head 的前端套件。
:::

局部頁面是位於 `src/pages/` 的頁面元件，但不是用來渲染完整的頁面。

和位於該目錄之外的其他元件一樣，這些檔案不會自動包含 `<!DOCTYPE html>`、`<head>`、scoped styles 和 scripts。

由於它們位於 `src/pages/` 目錄，產生的 HTML 仍然可透過對應到檔案路徑的網址存取。因此渲染套件（例：htmx、Stimulus、jQuery）能夠在不重新整理或前往新頁面的前提下，於客戶端存取並動態載入 HTML 片段。

局部頁面搭配渲染套件同樣能夠開發動態內容，是不使用 [Astro 群島](/zh-tw/concepts/islands/) 和 [`<script>` 標籤](/zh-tw/guides/client-side-scripts/) 時的替代方案。

能夠匯出值（例：`.astro`、`.mdx`）的頁面檔案即可標記為局部頁面。

在 `src/pages/` 目錄下的檔案內匯出以下指定值，便可將檔案設定為局部頁面：

```astro title="src/pages/partial.astro" ins={2}
---
export const partial = true;
---

<li>I'm a partial!</li>
```

`export const partial` 要能夠靜態識別。合法的值為：

- 布林值 __`true`__。
- 透過 import.meta.env 存取的環境變數，例如 `import.meta.env.USE_PARTIALS`。

### 與套件搭配使用

搭配 [htmx](https://htmx.org/) 這種套件，局部頁面可用來動態更新頁面部分區域。

以下範例中，`hx-post` 屬性對應到局部頁面的網址，該頁面的內容將會用來更新這個頁面特定的 HTML 元素。

```astro title="src/pages/index.astro" 'hx-post="/partials/clicked/"'
<html>
  <head>
    <title>My page</title>
    <script src="https://unpkg.com/htmx.org@1.9.6"
      integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
      crossorigin="anonymous"></script>
  </head>
</html>
<section>
  <div id="parent-div">Target here</div>

  <button hx-post="/partials/clicked/"
    hx-trigger="click"
    hx-target="#parent-div"
    hx-swap="innerHTML"
  >
      Click Me!
  </button>
</section>
```

對應到檔案路徑的 `.astro` 局部頁面必須存在，且要明確匯出值，將頁面標記為局部頁面。

```astro title="src/pages/partials/clicked.astro" {2}
---
export const partial = true;
---
<div>I was clicked!</div>
```

細節請見 [htmx 文件](https://htmx.org/docs/)。
